home *** CD-ROM | disk | FTP | other *** search
/ Belgian Amiga Club - ADF Collection / BS1 part 05.zip / BS1 part 5 / LSD.adf / docs / shrink.doc.pp / shrink.doc
Text File  |  1990-09-13  |  13KB  |  309 lines
  1.  
  2.  
  3.  
  4.                            Shrink User's Guide
  5.  
  6.                          Version 1.1 - June 1992
  7.  
  8.  
  9.                         Written by Matthias Meixner
  10.  
  11.                    Copyright (c) 1992 by Matthias Meixner
  12.                            All rights reserved
  13.                           Not for commercial use
  14.  
  15.  
  16.  
  17.  
  18.    1- Disclaimer
  19.    ~~~~~~~~~~~~~
  20.    The author cannot be held liable for the suitability or accuracy of this
  21.    manual and/or the program(s) it describes.  Any damage directly or
  22.    indirectly caused by the use or misuse of this manual and/or the program
  23.    it describes is the sole responsibility of the user her/him self.
  24.  
  25.  
  26.    2 - Copyright/Distribution
  27.    ~~~~~~~~~~~~~~~~~~~~~~~~~~
  28.    Shrink, (c) Copyright 1992 Matthias Meixner. All rights reserved. This
  29.    Program is FREEWARE, so no financial donations are required (but welcome).
  30.    This  program may be freely distributed as long as all documentation and
  31.    executable(s) remain unchanged and are included with the distribution.
  32.    Also no profit is to be made by selling this program.
  33.    Shrink V1.1 must not be added to other PD-libraries than AmigaLibDisks
  34.    from Fred Fish without my written permission. The price must not exceed
  35.    the costs of disk, package and mailing.
  36.  
  37.    3 - Introduction
  38.    ~~~~~~~~~~~~~~~~
  39.    Shrink is a new archiver for the Commodore-Amiga computer similar to
  40.    LHA, lharc or zoo. It is not as fast as LHA, but compression rate is
  41.    better than the rate of all these other archivers. Shrink uses a new
  42.    IFF - format for its archives, that is designed to handle archives with
  43.    other programs (see IFF-documentation).
  44.  
  45.  
  46.    4 - System requirements
  47.    ~~~~~~~~~~~~~~~~~~~~~~~
  48.    Shrink will run on any Amiga system with at least 512KB RAM an one
  49.    diskdrive. But for compressing large files more memory is needed, because
  50.    shrink loads all files completely into RAM to reduce diskaccess.
  51.    A 68020, 030 or 040 processor is very useful to reduce compression time.
  52.  
  53.  
  54.    5 - Command line syntax
  55.    ~~~~~~~~~~~~~~~~~~~~~~~
  56.    The command line syntax is as follows:
  57.  
  58.    shrink [-options] <Command> <Archive> [dest path] [pattern1] [pattern2] ..
  59.  
  60.    [-options] are optional, [dest path] is only needed for extraction and
  61.    must end with ':' or '/', patterns are optional in some cases and
  62.    sometimes needed (see documentation of commands).
  63.    Patterns are the normal amiga patterns like #? or #?(x|y). Komplex
  64.    patterns like (#?|#?.c) are not supported.
  65.  
  66.  
  67.    6 - Adding files to archive
  68.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  69.    There are several ways to add files to an archive. Shrink supports the
  70.    following commands to add files matching the pattern to the archive:
  71.  
  72.       'a':  (add)
  73.             Adds files to the archive if they are not already there.
  74.  
  75.       'aa': (add all)
  76.             Adds or replaces files in the archive. If the files was already
  77.             in the archive, its generation is increased by one.
  78.             (see generations)
  79.  
  80.       'f':  (freshen files)
  81.             Replaces a file in an archive if the file is newer than the file
  82.             in the archive. The generation of the older file is increased
  83.             by one. Files that have not been in the archive are not addes to
  84.             the archive.
  85.  
  86.       'u:   (update archive)
  87.             Files are added to the archive if they are not already in the
  88.             archive or are replaced in the archive if they are newer than
  89.             the files in the archive. In this case the generation is
  90.             increased by one.
  91.  
  92.    Options for adding files:
  93.    The compression method can be set using the -m option. (-m0 no compression
  94.    .. -m7 best compression [default]).
  95.    -r forces shrink to collect the files recursively, e.g. to compress
  96.    directories with subdirectories.
  97.    With the option -a shrink supports the archive flag. When the option is
  98.    set, only files with non-set archive flag are added to the archive. After
  99.    adding them to the archive, the archive flag is set.
  100.    -q (quiet mode) switches the progress indicator off when compressing.
  101.    With -p(n) you can force shrink to pack the archive after adding files
  102.    (see also "packing the archive").
  103.  
  104.    7 - Testing archives
  105.    ~~~~~~~~~~~~~~~~~~~~
  106.    The commands 't(n)' and 'ta' are used to test archives if they contain any
  107.    errors. 't(n)' tests generation n of all files matching the pattern. If no
  108.    pattern is given, shrink uses #? as default. 'n' Is a number between
  109.    1 and 255 and specifies the generation that shall be tested. If it is
  110.    ommitted shrink assumes generation 1.
  111.    'ta' tests all files that are contained in the archive. Therefore it does
  112.    not support any patterns.
  113.  
  114.  
  115.    8 - Deleting files
  116.    ~~~~~~~~~~~~~~~~~~
  117.    Using 't(n)' or 'ta' you can delete files from the archive. With 'tn' the
  118.    generation n of a file is deleted from the archive. 'ta' deletes all
  119.    generations of the file.
  120.    When you delete files from an archive they are not really removed from
  121.    the archive, only their generation is set to 256. They are only removed
  122.    when packing the archive (see packing the archive). As long as they are
  123.    not removed from the archive they can be recovered again (see recovering
  124.    deleted files).
  125.  
  126.    Using the option -p(n) you can force shrink to pack the archive after
  127.    deleting files (see also "packing the archive").
  128.  
  129.  
  130.    9 - Recovering deleted files
  131.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  132.    If you wish to get back deleted files or files with an older generation
  133.    you can use 'r(n)' to get back generation n of the file or 'ra' to get
  134.    back a deleted file. The generation of this file is set to 1. The
  135.    generation of the other files with the same name is increased by 1.
  136.    If there exist more than one file with the same name and the same
  137.    generation in an archive, you can use the -i(n) option to turn on the
  138.    file index mode. Then only the n-th file that matches the pattern is
  139.    referred by this command.
  140.  
  141.  
  142.    10 - Packing the archive
  143.    ~~~~~~~~~~~~~~~~~~~~~~~~
  144.    Packing is used to remove all deleted or older files from an archive.
  145.    'p(n)' removes all generations that are higher than n from the archive.
  146.    E.g. 'r255' removes all files with a generation higher than 255 i.e.
  147.    deleted files. Or if you only want to keep 5 generations of each file
  148.    use 'p5' to remove all older files. Shrink generates a backup-file when
  149.    packing an archive. This is disabled by using the -d option. After adding
  150.    or deleting files you can auto-pack the archive using the -p(n) option.
  151.  
  152.  
  153.    11 - Extracting files
  154.    ~~~~~~~~~~~~~~~~~~~~~
  155.    Extraction is done by using the command 'e(n)' or 'x(n)'. These commands
  156.    extract the generation n of the files matching the pattern. If n is not
  157.    given the first generation is extracted.
  158.    If you do not want the whole pathname to be extracted, use the -c option
  159.    to extract only the filenames. A special feature of this option is to cut
  160.    off part of the filename. This can be used to change the path during
  161.    extraction. For example the file ff500/c/MuchMore would be extracted as
  162.    df0:c/MuchMore by the following command:
  163.        shrink -cff500 x archive ff500/c/MuchMore
  164.    If you wish to set the archive flag of the extracted files. you can use
  165.    the -a option that does exactly this during extraction.
  166.    By using the index-file-mode with the -i(n) option one can refer to the
  167.    n-th file that matches generation and pattern. This is useful when there
  168.    are more than one file of the same name and generation in one archive.
  169.    -x switches long pathnames on. The last givem option -c or -x is the one
  170.    that is used for extraction.
  171.  
  172.  
  173.    12 - Extracting files on the screen
  174.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  175.    's(n)' extracts the n-th generation of the file on the screen. You can
  176.    use the same options that can be used for normal extraction.
  177.  
  178.  
  179.    13 - Listing the contents of an archive
  180.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  181.    'l(n)' or 'v(n)' prints the contents upto generation n of the archive on
  182.    the screen, sorted by name and generation. Use 'la' or 'va' to get a list
  183.    of all files and deleted files. It has the same effect as using 'l256'.
  184.    You can preset the generation using the -l(n) option.
  185.  
  186.  
  187.    14 - Other options
  188.    ~~~~~~~~~~~~~~~~~~
  189.    '-q' disables the progress indicator during compression and decompression.
  190.  
  191.  
  192.    15 - Default options
  193.    ~~~~~~~~~~~~~~~~~~~~
  194.    You can setup default options in the environment variable ShrinkOptions.
  195.    E.g. setenv ShrinkOptions "-c -p10 -l10".
  196.  
  197.  
  198.    16 - Technical info
  199.    ~~~~~~~~~~~~~~~~~~~
  200.    Shrink uses a dictionary from 1024 upto 65536 bytes for compression due to
  201.    the compression-mode. String down to 2 bytes are replaced by their
  202.    reference to achieve maximum compression. Shrink uses dynamic arithmetic
  203.    encoding instead of huffman encoding to get a better compression rate.
  204.    Shrink is the first archiver on the amiga that uses this method for best
  205.    compression rate.
  206.  
  207.  
  208.    17 - IFF-Archive-Format
  209.    ~~~~~~~~~~~~~~~~~~~~~~~
  210.    Shrink uses a new IFF format for its archive files.
  211.    The structure is as follows:
  212.  
  213.    FORM xxxx CDAF  ; Compressed Data Archive File
  214.         ^^^^ length of FORM
  215.  
  216.    NAME xxxx archivers_name ; This chunk must be the first chunk in the
  217.                             ; archive to determine the archiver that is
  218.                             ; required for compression and decompression
  219.                             ; of files in the archive. The other functions
  220.                             ; like deleting or recovering files should
  221.                             ; work with every archiver using this format
  222.  
  223.  
  224.    FILE xxxx                ; This must be the first chunk of every file
  225.                             ; contained in the archive
  226.       UBYTE Checksum        ; The sum of all bytes in this chunk must be zero
  227.       UBYTE Method,Version  ; Method and version of the compression method
  228.                             ; that was used to compress this file
  229.       UBYTE Generation      ; Generation of the file: 0=new .. 255=deleted
  230.       USHORT SystemID       ; System ID of the computer on which the file
  231.                             ; was compressed.
  232.       ULONG Filesize        ; Original size of the file, the compressed
  233.                             ; size of the file is the size of the BODY chunk
  234.       UBYTE Year,Month,Day  ; Date of the file (year since 1900)
  235.       UBYTE Hour,Mins,Secs  ; Time of the file
  236.       USHORT CRC            ; CRC Checksum of the uncompressed file
  237.       ULONG Protection      ; File attributes on the computer of SystemID
  238.       UBYTE Filname[]       ; The rest of the length of this chunk is used
  239.                             ; to store the filename. This enables filenames
  240.                             ; of any lenght
  241.  
  242.    BODY  xxxx               ; This chunk contains the compressed data of the
  243.                             ; file. This must be the last chunk of every
  244.                             ; file in the archive.
  245.  
  246.  
  247.    Between the chunks FILE and BODY there can be as many chunks as the
  248.    archiver needs to store additional information about the file and/or
  249.    compression. Therefore these chunks must not be removed when packing or
  250.    modifying archives. One of these chunks is the NOTE chunk:
  251.  
  252.    NOTE xxxx filenote
  253.  
  254.    It contains the filenote of the file.
  255.  
  256.  
  257.    18 - SystemID's
  258.    ~~~~~~~~~~~~~~~
  259.    AMIGA        'AM'
  260.    ATARI_ST     'ST'
  261.    ARCHIMEDES   'AR'
  262.    MS_DOS       'MS'
  263.    UNIX         'UX'
  264.    MAC          'MA'
  265.    HELIOS       'HE'
  266.  
  267.  
  268.    19 - History
  269.    ~~~~~~~~~~~~
  270.    V1.01b  First official release
  271.    V1.1    Shrink now handles files with a size of 65536 bytes correct.
  272.            Improoved speed on archivehandling.
  273.            Default options in ENV:ShrinkOptions
  274.            Autopacking of the archive with a,f,u,d
  275.            The compression rate is now calculated correctly for large files
  276.  
  277.  
  278.    20 - Known bugs
  279.    ~~~~~~~~~~~~~~~
  280.    Shrink adds the archive to itself, if the archive has already been
  281.    created.
  282.  
  283.  
  284.    21 - Something on bug reports
  285.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  286.    When sending in bug reports, please state exactly under what
  287.    circumstances the bug occurred, what equipment was used and what happened.
  288.    If possible also try to give me enough information to reproduce the bug.
  289.    It is very difficult to find bugs when you don't know exactly what
  290.    happened. Please don't just send messages like "it can't extract files
  291.    from archives sometimes", that really doesn't help me. If possible,
  292.    submit the offending file/archive to me so I can test it myself, or give
  293.    me a pointer where I can find the archive.
  294.  
  295.  
  296.    22 - Notes
  297.    ~~~~~~~~~~
  298.    Bug reports, suggestions, postcards, flames, criticism, contributions,
  299.    ideas, gifts, etc., etc., etc........... to:
  300.  
  301.  
  302.                      Matthias Meixner
  303.                      Sandberg 13
  304.                      W-6417 Hofbieber 2
  305.                      Germany
  306.  
  307.  
  308.  
  309.